🚀 Mac M4 本地 AI 抠图服务部署指南 (BiRefNet)

2025年12月16日

目标：在 macOS 上部署 BiRefNet SOTA 抠图模型硬件要求： Apple Silicon Mac (M1/M2/M3/M4) 最终效果：提供 Web 界面 (端口 8860) + API 接口，利用 NPU/GPU 极速抠图。

第一步：安装包管理器 (Homebrew)

如果你的 Mac 已经安装了 Homebrew，请跳过此步。

打开终端 (Terminal)，复制并运行以下命令：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

重要：配置环境变量安装完成后，终端底部会提示你运行两行命令（echo 开头的），一定要执行它们，否则无法使用 brew 命令。如果你错过了，可以手动执行：

(echo; echo 'eval "$(/opt/homebrew/bin/brew shellenv)"') >> /Users/$USER/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

第二步：安装 Python 环境管理 (Miniforge)

我们需要一个干净的 Python 环境。对于 Apple Silicon 芯片，Miniforge 是最佳选择（比 Anaconda 更轻，原生支持 M 芯片）。

安装 Miniforge:
```
brew install miniforge
```
初始化 Shell:
```
conda init zsh
```
生效配置: 关闭当前终端窗口，重新打开一个新的终端。

第三步：创建项目与环境

我们将所有文件放在 Documents/BiRefNet-Mac 目录下。

创建目录:

mkdir -p ~/Documents/BiRefNet-Mac
cd ~/Documents/BiRefNet-Mac

创建独立 Python 环境 (Python 3.10):

conda create -n birefnet python=3.10 -y

激活环境:
```
conda activate birefnet
```

(激活后，你的命令行前缀应该会变成 (birefnet))

第四步：安装依赖 (关键步骤)

我们将安装 PyTorch (支持 Mac GPU 加速) 和 BiRefNet 所需的库。

复制以下命令并在终端执行：

# 1. 安装 PyTorch 和 图像处理库
pip install torch torchvision torchaudio

# 2. 安装 HuggingFace 生态库 和 WebUI 库
pip install transformers timm pillow gradio accelerate

# 3. 安装模型特定的数学库 (补全之前的报错)
pip install einops kornia

第五步：写入代码 (app.py)

直接复制下面整块代码到终端中运行。这会自动在当前目录下生成配置好的 app.py 文件。

配置说明：已启用 Mac GPU (MPS) 加速，端口设定为 8860。

cat > app.py << 'EOF'
import gradio as gr
import torch
from transformers import AutoModelForImageSegmentation
from torchvision import transforms
from PIL import Image

# --- 1. 设备检测 (Mac M4 核心) ---
def get_device():
    if torch.backends.mps.is_available():
        print("✅ 成功激活 Mac M4 GPU (MPS 模式) - 性能全开")
        return "mps"
    return "cpu"

device = get_device()

# --- 2. 加载模型 ---
# 这里使用通用版 BiRefNet，效果最均衡
MODEL_ID = "ZhengPeng7/BiRefNet"
print(f"正在加载模型: {MODEL_ID} ...")
# trust_remote_code=True 是必须的，因为该模型包含自定义代码
model = AutoModelForImageSegmentation.from_pretrained(MODEL_ID, trust_remote_code=True)
model.to(device)
model.eval()

# --- 3. 预处理 ---
transform = transforms.Compose([
    transforms.Resize((1024, 1024)), # 想要更精细可改为 2048，但速度会变慢
    transforms.ToTensor(),
    transforms.Normalize(mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225]),
])

# --- 4. 核心推理逻辑 ---
def remove_background(image):
    if image is None: return None
    original_size = image.size
  
    # 图片转 Tensor 并移至 GPU
    input_tensor = transform(image).unsqueeze(0).to(device)
  
    # 推理 (不计算梯度，节省显存)
    with torch.no_grad():
        preds = model(input_tensor)[-1].sigmoid().cpu()
  
    # 生成 Mask 并还原尺寸
    pred = preds[0].squeeze()
    pred_pil = transforms.ToPILImage()(pred)
    mask = pred_pil.resize(original_size)
  
    # 合成 Alpha 通道
    image.putalpha(mask)
    return image

# --- 5. 启动 Web 服务 ---
with gr.Blocks(title="BiRefNet Local") as demo:
    gr.Markdown("## ⚡️ BiRefNet 本地版 (Powered by Mac M4)")
    with gr.Row():
        input_img = gr.Image(type="pil", label="上传图片")
        output_img = gr.Image(type="pil", label="抠图结果", format="png")
  
    btn = gr.Button("开始抠图", variant="primary")
    btn.click(fn=remove_background, inputs=input_img, outputs=output_img)

if __name__ == "__main__":
    # 允许局域网访问，端口 8860
    demo.launch(server_name="0.0.0.0", server_port=8860)
EOF

第六步：首次运行与模型下载

由于国内连接 HuggingFace 可能不稳，我们先设置镜像加速，然后前台运行一次以确保模型下载成功。

# 设置 HF 镜像 (临时生效)
export HF_ENDPOINT=https://hf-mirror.com

# 启动！
python app.py

观察终端： 等待进度条走完（约 580MB）。
成功标志： 看到 Running on local URL: http://0.0.0.0:8860。
测试： 打开浏览器访问 http://localhost:8860，试着上传一张图片。
退出： 测试没问题后，按 Ctrl + C 停止程序。

第七步：配置后台静默运行 (生产模式)

为了让你关闭终端后服务依然可用，我们需要把它挂在后台。

启动脚本 (含日志):

nohup python -u app.py > app.log 2>&1 &

**验证服务:**访问 http://localhost:8860
查看日志 (可选):

tail -f app.log

运维管理命令 (建议收藏)

以后你需要重启机器或者重新开启服务时：

1. 开启服务：

cd ~/Documents/BiRefNet-Mac
conda activate birefnet
nohup python -u app.py > app.log 2>&1 &

2. 关闭服务：

# 查找占用 8860 端口的进程并强制关闭
lsof -t -i:8860 | xargs kill -9

3. 查看运行状态：

ps -ef | grep app.py

现在，你的 Mac mini M4 已经变成了一台高性能的本地抠图服务器，且完全不依赖 Docker，性能损耗为零。